Skip to content

Clarify positional argument handling in TypedDict constructor#2248

Open
BHUVANSH855 wants to merge 9 commits intopython:mainfrom
BHUVANSH855:typeddict-positional-args
Open

Clarify positional argument handling in TypedDict constructor#2248
BHUVANSH855 wants to merge 9 commits intopython:mainfrom
BHUVANSH855:typeddict-positional-args

Conversation

@BHUVANSH855
Copy link
Copy Markdown

This PR updates the TypedDict constructor specification to clarify handling of positional arguments.

The current spec states that only keyword arguments are allowed, but this does not fully reflect runtime behavior and differences across type checkers.

This change:

  • Allows type checkers to accept a single positional argument of TypedDict type
  • Explicitly discourages other positional forms (e.g., dicts, sequences)
  • Adds conformance tests to define expected behavior

This aims to improve consistency while avoiding unsafe or ambiguous cases.

@srittau srittau added the topic: typing spec For improving the typing spec label Apr 7, 2026
@BHUVANSH855
Copy link
Copy Markdown
Author

Hi @srittau @JelleZijlstra,

Just checking in regarding the latest updates to this PR.
Kindly let me know if any further changes are required.

Thank you!

@carljm
Copy link
Copy Markdown
Member

carljm commented Apr 12, 2026

I am not convinced that we should discourage type checkers from accepting additional forms.

@BHUVANSH855
Copy link
Copy Markdown
Author

I am not convinced that we should discourage type checkers from accepting additional forms.

Thanks for the feedback @carljm,

I’ve updated the wording to remove the restriction on additional positional forms and instead clarify that only the specified behavior is required, while type checkers may choose to support additional forms.

Please let me know if this looks good now.
Kindly review it again.

Copy link
Copy Markdown
Member

@carljm carljm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I'm generally fine with this leave-it-up-to-type-checkers approach; it's good to add something to the spec text to make it more explicit, even if we don't strictly require a particular behavior. Would like to know what @JelleZijlstra and others think.

Comment thread docs/spec/typeddict.rst
whose type is a TypedDict. In this case, the resulting value is initialized from
that argument.

Type checkers may choose to accept additional forms of positional arguments,
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Type checkers may choose to accept additional forms of positional arguments,
Type checkers may choose to accept additional forms of positional arguments, and/or mixed positional/keyword calls,

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the feedback! @carljm

I initially added wording to clarify that type checkers may accept additional positional forms, but based on the discussion, I’ve simplified the spec to avoid implying specific behavior beyond what is clearly supported.

For now, the spec only describes the keyword-based constructor and the case of a single TypedDict positional argument, without constraining or explicitly encouraging other forms.

Happy to refine this further if we reach consensus on specific patterns that should be required.

Copy link
Copy Markdown
Member

@JelleZijlstra JelleZijlstra left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure this change is an improvement. If we're going to expand the spec here, I'd rather we clearly list out some patterns that we want to require. It's going to require some work though to sort out what is reasonable to require.

TD1(td2)

# invalid positional arguments
TD1({"a": 1}) # E
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we require an error? These both seem like valid calls.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point — I’ve updated the conformance tests to remove the requirement for errors in those cases, since such calls can be valid and behavior may vary across type checkers.

Regarding the spec change, I’ve also simplified the wording to avoid over-specifying behavior. I agree that if we expand this area further, it would be better to clearly define specific patterns to require.

Happy to help explore and document those patterns if needed.
@JelleZijlstra

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

topic: typing spec For improving the typing spec

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants